Skip to content

docs: require a frontmatter description on every page - #4865

Draft
thetaPC wants to merge 2 commits into
chore/renovate-automergefrom
chore/require-descriptions
Draft

thetaPC wants to merge 2 commits into
chore/renovate-automergefrom
chore/require-descriptions

Conversation

@thetaPC

@thetaPC thetaPC commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Issue URL: N/A

What is the current behavior?

  • 384 pages set their description in a <head> meta tag. Docusaurus doesn't read it, so og:description and llms.txt fall back to an excerpt of the page, the path that leaked {/* #id */} comments into descriptions.
  • 66 pages have no description at all.
  • exclude: ['README.md'] in the docs config replaces Docusaurus's default excludes, so files starting with _ are built as pages. The five config examples imported by developing/config.mdx are published as stray pages titled "index", in docs and v8.

What is the new behavior?

  • Every page in docs and v8 has a description in its frontmatter: 384 moved from <head> and 66 new.
  • npm run lint fails on a page without a frontmatter description, or with one in <head>. Generated native and cli pages, and _ files, are skipped.
  • The lint parses frontmatter with remark-frontmatter, so a < in a description no longer breaks it.
  • The docs config restores Docusaurus's default excludes, and the five config examples become _<name>.mdx, removing the 10 stray pages.
  • CONTRIBUTING describes both rules, and why a longer <title> still belongs in <head>.

Does this introduce a breaking change?

  • Yes
  • No

Other information

Compared with a build of #4862, the 384 moved pages change only og:description, which now matches the unchanged meta description. The 66 new ones change both tags, and the stray pages are gone. Every other page and Markdown version is identical.

Stacked on #4864.

@thetaPC
thetaPC added this pull request to stack #4861 November 18, 2026 01:35
@vercel

vercel Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
ionic-docs Ready Ready Preview Nov 18, 2026 1:42am UTC

Request Review

This branch was successfully deployed

1 active deployment
Preview — 632189eb Deployed Nov 18, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant